Release 10.1A: OpenEdge Development:
Messaging and ESB

Message acknowledgement, forwarding, and recovery

A client sends an acknowledgement to tell the SonicMQ Broker that the client received and processed a message and does not need to receive that message again. Acknowledgement of a message prevents the message and all previous messages from being delivered to that session again.

Table 4–23 lists the methods the application uses to set message acknowledgement.

Table 4–23: Acknowledging and forwarding messages 

Setting	Getting
setSingleMessageAcknowledgement procedure setNoAcknowledge procedure acknowledgeAndForward procedure	getSingleMessageAcknowledgement function getNoAcknowledge function

The sections that follow describe automatic message acknowledgement, preventing message acknowledgement, and message recovery.

Automatic message acknowledgement

With the 4GL-JMS API, an incoming message is acknowledged automatically when the message handler finishes execution. Acknowledgement is sent on the request for the next message, improving performance.

A client or communication failure between the time the message handler finishes execution and the time the 4GL-JMS implementation sends the acknowledgement can result in the messages being redelivered (according to the JMS message redelivery rules). An application can use a transacted session to avoid this message redelivery problem.

Unlike Java–JMS, the 4GL-JMS API does not support the explicit acknowledgement of messages or the “lazy” acknowledgement of messages (the JMS CLIENT_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE modes).

Preventing message acknowledgement

A 4GL application can explicitly prevent acknowledgement of a message by calling the setNoAcknowledge procedure of the Message Consumer object. (The Message Consumer object is passed as a parameter to the message-handling procedure.) The setNoAcknowledge procedure is typically used when the application wants to receive the same message again because of an error in processing it, or when receipt of a group of messages is to be signaled by explicit acknowledgement of only the last message in the group.

Single-message acknowledgement

Normally, a 4GL client application automatically acknowledges a message when the message handler procedure completes. In SINGLE_MESSAGE_ACKNOWLEDGE mode, however, each message requires its own acknowledgement; if you choose not to acknowledge a message, it is never acknowledged.

To turn on SINGLE_MESSAGE_ACKNOWLEDGE mode, a 4GL client application calls the setSingleMessageAcknowledgement procedure of the session handle with the input parameter set to TRUE. To turn off this mode, the application calls the same method with the input parameter set to FALSE.

Message recovery

If an application wants to receive all unacknowledged messages again, it can call the recover procedure in the Session object. If the recover procedure is called on a session stopped by the stopReceiveMessages procedure, the session is recovered and message delivery is restarted.

Example

Consider the following scenario:

A client retrieves a message from a broker’s queue.
The broker wants to be notified when the message reaches its ultimate destination.
The ultimate destination is a remote queue.
The client sends the message on its way.

To acknowledge receipt of a message whose ultimate destination is a remote queue, you might enclose the message and acknowledgement in a single transaction; but this introduces the overhead and complexity of transaction processing. SonicMQ provides a cleaner solution, embodied in the following steps:

Run the setSingleMessageAcknowledgement procedure to set the session to SINGLE_MESSAGE_ACKNOWLEDGE.
Run the acknowledgeAndForward procedure within the message event handler, specifying a destination queue name, the original message handle, and optional message-delivery properties (priority, time to live, and persistency). If the method is successful, the message is acknowledged and forwarded in a single atomic operation.